home *** CD-ROM | disk | FTP | other *** search
/ PC World 2006 July & August / PCWorld_2006-07-08_cd.bin / komunikace / apache / apache_2[1].2.2-win32-x86-no_ssl.msi / Data1.cab / _F98A56DE536E3E4F4AF55FD1C9FC6281 < prev    next >
Encoding:
Text File  |  2005-02-04  |  5.9 KB  |  167 lines
  1. /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
  2.  * applicable.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16.  
  17. #ifndef APR_PROC_MUTEX_H
  18. #define APR_PROC_MUTEX_H
  19.  
  20. /**
  21.  * @file apr_proc_mutex.h
  22.  * @brief APR Process Locking Routines
  23.  */
  24.  
  25. #include "apr.h"
  26. #include "apr_pools.h"
  27. #include "apr_errno.h"
  28.  
  29. #ifdef __cplusplus
  30. extern "C" {
  31. #endif /* __cplusplus */
  32.  
  33. /**
  34.  * @defgroup apr_proc_mutex Process Locking Routines
  35.  * @ingroup APR 
  36.  * @{
  37.  */
  38.  
  39. /** 
  40.  * Enumerated potential types for APR process locking methods
  41.  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
  42.  *          APR_LOCK_foo.  Only APR_LOCK_DEFAULT is portable.
  43.  */
  44. typedef enum {
  45.     APR_LOCK_FCNTL,         /**< fcntl() */
  46.     APR_LOCK_FLOCK,         /**< flock() */
  47.     APR_LOCK_SYSVSEM,       /**< System V Semaphores */
  48.     APR_LOCK_PROC_PTHREAD,  /**< POSIX pthread process-based locking */
  49.     APR_LOCK_POSIXSEM,      /**< POSIX semaphore process-based locking */
  50.     APR_LOCK_DEFAULT        /**< Use the default process lock */
  51. } apr_lockmech_e;
  52.  
  53. /** Opaque structure representing a process mutex. */
  54. typedef struct apr_proc_mutex_t apr_proc_mutex_t;
  55.  
  56. /*   Function definitions */
  57.  
  58. /**
  59.  * Create and initialize a mutex that can be used to synchronize processes.
  60.  * @param mutex the memory address where the newly created mutex will be
  61.  *        stored.
  62.  * @param fname A file name to use if the lock mechanism requires one.  This
  63.  *        argument should always be provided.  The lock code itself will
  64.  *        determine if it should be used.
  65.  * @param mech The mechanism to use for the interprocess lock, if any; one of
  66.  * <PRE>
  67.  *            APR_LOCK_FCNTL
  68.  *            APR_LOCK_FLOCK
  69.  *            APR_LOCK_SYSVSEM
  70.  *            APR_LOCK_POSIXSEM
  71.  *            APR_LOCK_PROC_PTHREAD
  72.  *            APR_LOCK_DEFAULT     pick the default mechanism for the platform
  73.  * </PRE>
  74.  * @param pool the pool from which to allocate the mutex.
  75.  * @see apr_lockmech_e
  76.  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
  77.  *          APR_LOCK_foo.  Only APR_LOCK_DEFAULT is portable.
  78.  */
  79. APR_DECLARE(apr_status_t) apr_proc_mutex_create(apr_proc_mutex_t **mutex,
  80.                                                 const char *fname,
  81.                                                 apr_lockmech_e mech,
  82.                                                 apr_pool_t *pool);
  83.  
  84. /**
  85.  * Re-open a mutex in a child process.
  86.  * @param mutex The newly re-opened mutex structure.
  87.  * @param fname A file name to use if the mutex mechanism requires one.  This
  88.  *              argument should always be provided.  The mutex code itself will
  89.  *              determine if it should be used.  This filename should be the 
  90.  *              same one that was passed to apr_proc_mutex_create().
  91.  * @param pool The pool to operate on.
  92.  * @remark This function must be called to maintain portability, even
  93.  *         if the underlying lock mechanism does not require it.
  94.  */
  95. APR_DECLARE(apr_status_t) apr_proc_mutex_child_init(apr_proc_mutex_t **mutex,
  96.                                                     const char *fname,
  97.                                                     apr_pool_t *pool);
  98.  
  99. /**
  100.  * Acquire the lock for the given mutex. If the mutex is already locked,
  101.  * the current thread will be put to sleep until the lock becomes available.
  102.  * @param mutex the mutex on which to acquire the lock.
  103.  */
  104. APR_DECLARE(apr_status_t) apr_proc_mutex_lock(apr_proc_mutex_t *mutex);
  105.  
  106. /**
  107.  * Attempt to acquire the lock for the given mutex. If the mutex has already
  108.  * been acquired, the call returns immediately with APR_EBUSY. Note: it
  109.  * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine
  110.  * if the return value was APR_EBUSY, for portability reasons.
  111.  * @param mutex the mutex on which to attempt the lock acquiring.
  112.  */
  113. APR_DECLARE(apr_status_t) apr_proc_mutex_trylock(apr_proc_mutex_t *mutex);
  114.  
  115. /**
  116.  * Release the lock for the given mutex.
  117.  * @param mutex the mutex from which to release the lock.
  118.  */
  119. APR_DECLARE(apr_status_t) apr_proc_mutex_unlock(apr_proc_mutex_t *mutex);
  120.  
  121. /**
  122.  * Destroy the mutex and free the memory associated with the lock.
  123.  * @param mutex the mutex to destroy.
  124.  */
  125. APR_DECLARE(apr_status_t) apr_proc_mutex_destroy(apr_proc_mutex_t *mutex);
  126.  
  127. /**
  128.  * Destroy the mutex and free the memory associated with the lock.
  129.  * @param mutex the mutex to destroy.
  130.  * @note This function is generally used to kill a cleanup on an already
  131.  *       created mutex
  132.  */
  133. APR_DECLARE(apr_status_t) apr_proc_mutex_cleanup(void *mutex);
  134.  
  135. /**
  136.  * Return the name of the lockfile for the mutex, or NULL
  137.  * if the mutex doesn't use a lock file
  138.  */
  139.  
  140. APR_DECLARE(const char *) apr_proc_mutex_lockfile(apr_proc_mutex_t *mutex);
  141.  
  142. /**
  143.  * Display the name of the mutex, as it relates to the actual method used.
  144.  * This matches the valid options for Apache's AcceptMutex directive
  145.  * @param mutex the name of the mutex
  146.  */
  147. APR_DECLARE(const char *) apr_proc_mutex_name(apr_proc_mutex_t *mutex);
  148.  
  149. /**
  150.  * Display the name of the default mutex: APR_LOCK_DEFAULT
  151.  */
  152. APR_DECLARE(const char *) apr_proc_mutex_defname(void);
  153.  
  154. /**
  155.  * Get the pool used by this proc_mutex.
  156.  * @return apr_pool_t the pool
  157.  */
  158. APR_POOL_DECLARE_ACCESSOR(proc_mutex);
  159.  
  160. /** @} */
  161.  
  162. #ifdef __cplusplus
  163. }
  164. #endif
  165.  
  166. #endif  /* ! APR_PROC_MUTEX_H */
  167.